/**
 * @addtogroup brd_ext_rtc
 * brd_ext_rtc
 * @{
 */
/**
 * @file brd_ext_rtc.h
 * @brief 外部实时时钟板级层
 * @par 修改日志
 * <table>
 * <tr><th>Date         <th>Version     <th>Author       <th>Description
 * <tr><td>2021-03-12   <td>1.0         <td>软件工程院    <td>创建初始版本
 * <tr><td>2023-08-23   <td>1.1         <td>软件工程院    <td>增加休眠操作的接口
 * @par 示例
 * @code
 * 创建一个设备. 
   TTime time;
   ...
   /// 正常工作时
   Brd_ExtRtcOpen();
   ...
   Brd_ExtRtcGetTime(&time);
   Brd_ExtRtcSetTime(&time);
   ...
   Brd_ExtRtcClose();
   ...
   /// 系统休眠前
   Brd_ExtRtcOpen();
   Brd_ExtRtcStartTimer(60);
   Brd_ExtRtcClose();
   
   /// 系统休眠唤醒后
   Brd_ExtRtcOpen();
   Brd_ExtRtcStopTimer();
   Brd_ExtRtcClose();

   /// v1.1
   /// 系统休眠前
   Brd_ExtRtcStartWakeUpTimer(60);

   /// 系统休眠唤醒后
   Brd_ExtRtcStopWakeUpTimer();

====================2.1 休眠定时器用法===========================
   Brd_DisableGlobalIrq();///< 关闭全局中断
   /// 开启外部rtc定时唤醒
   Brd_ExtRtcStartWakeUpTimer(60);
   ...
   /// 进入休眠
   Brd_PmcSetMode(kBrd_PmcIdxxx);
   /// 退出休眠
   Brd_PmcSetMode(kBrd_PmcIdxxx);
   ...
   /// 在开全局中断前停止外部rtc定时
   Brd_ExtRtcStopWakeUpTimer();
   ...
   Brd_EnableGlobalIrq();///< 开全局中断
   ...
 * @endcode 
 * @copyright 杭州鸿泉物联网技术股份有限公司
 */

#ifndef _BRD_EXT_RTC_H_
#define _BRD_EXT_RTC_H_

#include <ofc_types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * 打开设备
 * @return 当返回值 >= 0 时, 表示打开成功 \n
 *         当返回值 < 0 时, 表示打开失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcOpen(void);

/**
 * 关闭设备
 * @return 当返回值 >= 0 时, 表示关闭成功 \n
 *         当返回值 < 0 时, 表示关闭失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcClose(void);

/**
 * 获取当前时间的秒数
 * @param seconds: 当前时间的秒数
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcGetTime(TTime *seconds);

/**
 * 设置当前时间的秒数
 * @param seconds: 设置的RTC时间(时间非BCD码)
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcSetTime(TTime seconds);

/**
 * 设置超时时间,并启动定时器
 * @note RTC在经过timeout秒后, 将产生超时警告, 常用于休眠唤醒. 在休眠前设置定时时间, 休眠唤醒后,
         调用Brd_ExtRtcStopTimer关闭定时器.
         可通过外部中断信号查询是否发生了超时, 参见[Brd_TExtIntIdTag](@ref kBrd_ExtIntIdRtc)
 * @param timeout: 定时器溢出时间, 单位是秒
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcStartTimer(TTime timeout);

/**
 * 关闭定时器
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcStopTimer(void);

/**
 * 设置闹钟时间,并启动闹钟
 * @note RTC在到达seconds(时间戳)后, 将产生超时警告, 常用于休眠唤醒. 在休眠前设置时间戳时间, 休眠唤醒后, \n
 *       调用Brd_ExtRtcStopAlarm关闭闹钟,否则中断引脚一直拉低. \n
 *       可通过外部中断信号查询是否产生闹钟, 参见[Brd_TExtIntIdTag](@ref kBrd_ExtIntIdRtc) \n
 *       需要注意的是闹钟参数关心日、时、分，即最大时长为不能超过月，精度只能到分
 * @param seconds: 闹钟时间, 单位是秒
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcStartAlarm(TTime seconds);

/**
 * 关闭闹钟
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcStopAlarm(void);

/**
 * 设置休眠唤醒超时时间,并启动休眠唤醒定时器
 * @note 只能用于休眠唤醒
 * @param timeout: 定时器溢出时间, 单位是秒
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcStartWakeUpTimer(TTime timeout);

/**
 * 关闭休眠唤醒定时器
 * @note 1.只能用于休眠唤醒
 *       2.此函数要在打开全局中断前, 调用关闭定时器具体可参见@code 2.1
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 < 0 时, 表示失败, 参见[brd_def](@ref Brd_TErrorCode)
 */
Int32 Brd_ExtRtcStopWakeUpTimer(void);

#ifdef __cplusplus
}  ///< extern "C"
#endif

#endif // _BRD_EXT_RTC_H_
/**
 * @} 
 */
